Mobile to Address API - v2

This document highlights details of the Mobile to Address API - v2.

API Description

Objective

The Mobile to Address API - v2 retrieves a user's verified address and contact details using their mobile number.

Input	Output
The user's mobile number and consent	The user's address information

API URL

https://ind-engine.thomas.hyperverge.co/v1/mobileToAddressV2

API Endpoint

mobileToAddressV2

Overview

The Mobile to Address API - v2 API is RESTful and uses standard HTTP verbs and status codes. The requests are in JSON format and responses are in JSON format.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the Mobile to Address API - v2.

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the details of the parameters required for the Mobile to Address API - v2's request body:

Parameter	Mandatory or Optional	Description
mobile	Mandatory	10 digit mobile number
consent	Mandatory	Consent flag indicating user permission (yes/no)

Request

The following code snippet demonstrates a standard curl request for the Mobile to Address API - v2:

curl --location 'https://ind-engine.thomas.hyperverge.co/v1/mobileToAddressV2' \
--header 'Content-Type: application/json' \
--header 'appId: <appId>' \
--header 'appKey: <appKey>' \
--header 'transactionId: <transactionId>' \
--data '{
  "mobile": "<Enter_the_Mobile_Number>",
  "consent": "<Enter_yes_or_no>"
}'

Success Response

The following code snippet demonstrates a success response from the Mobile to Address API - v2:

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "address": "<Address_Information>",
        "date": "<Delivery_Date>"
    },
    "metadata": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Success Response Details

The following table outlines the details of the success response from the API:

Parameter	Type	Description
status	string	The API status indicator
statusCode	integer	The HTTP-like status code for the API response
result	object	The main result object containing all response data
address	string	The verified and structured address returned from the API
date	string	The latest delivery date in ISO 8601 format
metadata	object	The metadata object containing request tracking information
requestId	string	The unique request identifier generated for tracing purposes
transactionId	string	The client-provided transaction identifier to correlate API calls

Failure Response

The following is a failure response from the API:

{
    "status": "failure",
    "statusCode": 404,
    "error": "Record Not Found",
    "metadata": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Error Responses

The following are some error responses from the API:

Invalid Mobile Number

{
    "status": "failure",
    "statusCode": 400,
    "error": "Invalid mobile number",
    "metadata": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Consent Empty

{
    "message": "Input Validation Error: consent is not one of enum values: yes,no",
    "statusCode": 400,
    "status": "failure"
}

Consent Undefined

{
    "message": "Input Validation Error: requires property \"consent\"",
    "statusCode": 400,
    "status": "failure"
}

Mobile Empty

{
    "message": "Input Validation Error: mobile does not meet minimum length of 10",
    "statusCode": 400,
    "status": "failure"
}

Mobile Undefined

{
    "message": "Input Validation Error: requires property \"mobile\"",
    "statusCode": 400,
    "status": "failure"
}

Missing/Invalid Credentials

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

Internal Server Error

{
    "status": "failure",
    "statusCode": 500,
    "error": "Internal Server Error"
}

External Source Downtime

{
    "status": "failure",
    "statusCode": 503,
    "error": "External source downtime"
}

Failure and Error Response Details

A failure or error response from the module contains a failure status, with a relevant status code and error message.

The following table lists all error responses:

Status Code	Error Message	Description
400	Invalid mobile number	The mobile number provided is not in valid format
400	Input Validation Error: consent is not one of enum values: yes,no	The consent is empty or not one of the allowed values(yes or no)
400	Input Validation Error: requires property "consent"	The consent is missing from the request
400	Input Validation Error: mobile does not meet minimum length of 10	The mobile number entered is empty or does not meet the minimum length requirement
400	Input Validation Error: requires property "mobile"	The mobile number is missing from the request
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values
404	Record Not Found	The mobile number provided does not exist in the database
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution
503	External source downtime	Please contact the HyperVerge team for resolution